Paylov Payment Gateway Checkout API Руководство по интеграции

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

STEP 1: Регистрация обратного вызова URL

Прежде чем инициировать транзакции, мерчант должен предоставить обратный вызов URL, куда Paylov будет отправлять обновления транзакций.

Необходимые детали:

Поле	Описание
Callback URL	Your server endpoint to receive payment notifications
Login	Логин мерчанта API
Password	Пароль мерчанта API

Paylov использует базовую аутентификацию при отправке сообщений на ваш обратный вызов URL.

Пример обратного вызова URL:

 https://your-server-domain.com/payment/callback/

STEP 2: Создать ссылку для оплаты

Мерчанты генерируют платежную ссылку с закодированными параметрами, которую клиенты открывают, чтобы перейти к размещенному платежному интерфейсу Paylov.

Конечная точка:

https://my.paylov.uz/checkout/create/{base64_encoded_params}

Важно

my.paylov.uz используется только для Checkout API. Для остальных API используйте BASE_URL.

Пример (в кодировке Base64):

https://my.paylov.uz/checkout/create/bWVyY2hhbnRfaWQ9MmVmNGE4OTYtOGRhMi00OGE0LTlhZjMtMjYwN2U2OTIxMGVjJmFtb3VudD01MDAmY3VycmVuY3lfaWQ9ODYwJnJldHVybl91cmw9aHR0cHMlM0ElMkYlMkZnb29nbGUuY29tJmFtb3VudF9pbl90aXlpbj1UcnVlJmFjY291bnQub3JkZXJfaWQ9MTIzMw==

Параметры (запрос в кодировке Base64):

Параметр	Описание
merchant_id	Unique merchant identifier (UUID)
amount	Сумма к оплате
currency_id	Код валюты (860 для UZS, 840 для USD)
return_url	Перенаправление URL после завершения оплаты
amount_in_tiyin	True, если сумма указана в тийинах (UZS центов)
account.order_id	Optional internal order reference

STEP 3: Поток транзакции

1. Перенаправление клиентов

После открытия ссылки для оплаты клиент перенаправляется на интерфейс оплаты Paylov.

При успешной или неудачной оплате:

• Клиент перенаправляется на return_url.
• Ваш сервер получает уведомление об обратном вызове для проверки и обработки.

Обратные вызовы между серверами

Paylov отправляет два типа запросов на ваш обратный вызов URL для проверки и подтверждения:

транзакция.check – проверить транзакцию

Paylov использует этот метод для проверки деталей транзакции перед выполнением фактического платежа.

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

Имя	Имя	Описание
account	dict	Поля, определенные мерчантом (например, order_id)
amount	int	Сумма в полной валюте (например, 500 UZS)
amount_tiyin	int	Сумма в тиинах (например, 50000)
curreny	int	Код валюты (860 = UZS, 840 = USD)

Пример запроса

{
  "jsonrpc": "2.0",
  "id": 1234567,
  "method": "transaction.check",
  "params": {
    "account": {
      "order_id": 12
    },
    "amount": 500,
    "amount_tiyin": 50000,
    "currency": 860
  }
}

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

{
  "jsonrpc": "2.0",
  "id": 1234567,
  "result": {
    "status": "0",
    "statusText": "OK"
  }
}

Дополнительные коды состояния см. в разделе Коды состояния.

транзакция.perform – Завершить транзакцию

Этот метод вызывается Paylov после подтверждения пользователем платежа.

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

Имя	Имя	Описание
transaction_id	UUID4	Уникальный идентификатор транзакции
account	dict	Поля, определенные мерчантом (например, order_id)
amount	int	Сумма платежа
amount_tiyin	int	Сумма платежа в тиыне
currency	int	860 или 840

Пример запроса

{
  "jsonrpc": "2.0",
  "id": 1234567,
  "method": "transaction.perform",
  "params": {
    "transaction_id": "9bd1a92b-5cce-47c8-a2df-99a20836ab9e",
    "account": {
      "order_id": 12
    },
    "amount": 500,
    "amount_tiyin": 50000,
    "currency": 860
  }
}

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

{
  "jsonrpc": "2.0",
  "id": 1234567,
  "result": {
    "status": "0",
    "statusText": "OK"
  }
}

Дополнительные коды состояния см. в разделе Коды состояния.

Краткое описание процесса интеграции

Шаг	Действие	Направление
1	Мерчант обеспечивает обратный звонок + аутентификацию	Merchant → Paylov
2	Мерчант создает ссылку для оплаты	Мерчант → Клиент
3	Клиент открывает ссылку и платит	Заказчик → Paylov
4	Paylov подтверждает транзакцию	Paylov → Merchant
5	Paylov совершает сделку	Paylov → Merchant
6	Клиент перенаправляется на возврат URL	Paylov → Клиент