Перейти к основному содержимому

Виджет оплаты с использованием биллинг системы поставщика услуг

Биллинг система поставщика услуг призвана сделать обработку платежей более быстрой и безопасной. Также она позволяет не допустить повторной оплаты заказа и своевременно информировать пользователя о проблемах оплаты. URL для вызова методов API настраиваются в личном кабинете поставщика услуг. Перед использованием этого API для реальных платежей, имеется возможность протестировать вызовы API из личного кабинета поставщика услуг.

Получение информации о платеже (Info)​

Метод реализует получение информации о платеже перед его оплатой.

Запрос содержит:

  • MERCHANT_TRANS_ID - идентификатор платежа в биллинг системе партнера
  • SIGN_TIME - Время подписания запроса в миллисекундах
  • SIGN_STRING - Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . MERCHANT_TRANS_ID . SIGN_TIME ), где SECRET_KEY секретный ключ поставщика услуг.
Пример запроса
{
  "MERCHANT_TRANS_ID": "7",
  "SIGN_TIME": 1503638389658,
  "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Ответ содержит:

Пример ответа биллинг системы поставщика услуг
{
  "ERROR": "0",
  "ERROR_NOTE": "Success",
  "PARAMETERS": {
    "full_name": "Test Test",
    "balance": "1000",
    "email": "test@test.uz"
  }
}

Проверка и подтверждение платежа (PAY URL)​

Метод реализует проверку актуальности платежа в биллинг системе поставщика услуг, а именно:

  • Наличие сформированного заказа/логина/номера лицевого счета в биллинг системе поставщика услуг, его актуальность, а также возможность отпустить указанный в заказе товар или услугу.
  • Актуальность суммы заказа и статуса оплаты.

На данный запрос поставщик услуг должен вернуть состояние заказа/логина/номера лиц.счета:

  • Заказ/логин/номер лиц.счета и сумма актуальны, ожидает оплаты. При получении данного статуса со стороны системы PaySys завершит оплату и будет отправлено уведомлении о завершении платежа.
  • Заказ/логин/номер лиц.счета неактуален (отменен). При данном ответе со стороны PaySys будет отправлено уведомлении о завершении платежа с признаком отмены платежа.

Важно! Необходимо при вызове этого метода проверять наличие оплаченных/отменных платежей в системе биллинга поставщика услуг по признаку AGR_TRANS_ID для предотвращения повторного списания средств с карточки/кошелька пользователя.

Запрос содержит:

  • ENVIRONMENT - окружение для выполнения метода: "live" - действительные платежи; "sandbox" - тестовые платежи.
  • VENDOR_ID - Идентификатор поставщика в системе PaySys
  • PAYMENT_ID - Идентификатор платежной системы в системе PaySys
  • PAYMENT_NAME - Наименование платежной системы
  • AGR_TRANS_ID - Идентификатор платежа в системе PaySys
  • MERCHANT_TRANS_ID - Идентификатор заказа (лицевого счета, подписки, пользователя) (string) в биллинг системе поставщика услуг
  • MERCHANT_TRANS_AMOUNT - Сумма оплаты в сумах или в долларах (float) (пример в сумах: 500; пример в долларах: 1.99)
  • MERCHANT_TRANS_DATA - Детали платежа из биллинг системы поставщика услуг. Данные кодируются методом Base64: base64_encode(json_encode('{"full_name":"Test Test","balance":"1000","email":"test@test.uz"}')); Передаются, если были получены в запросе о дополнительной информации заказа
  • SIGN_TIME - Время подписания запроса в миллисекундах
  • SIGN_STRING - Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_ID . PAYMENT_ID . PAYMENT_NAME . MERCHANT_TRANS_ID . MERCHANT_TRANS_AMOUNT . ENVIRONMENT . SIGN_TIME ) , где SECRET_KEY секретный ключ поставщика услуг.
Пример запроса
{
  "ENVIRONMENT": "sandbox",
  "VENDOR_ID": 902345,
  "PAYMENT_ID": 1,
  "PAYMENT_NAME": "Click",
  "AGR_TRANS_ID": 1503639319870,
  "MERCHANT_TRANS_ID": "7",
  "MERCHANT_TRANS_AMOUNT": 1000,
  "MERCHANT_TRANS_DATA": "eyJwYXJhbV9rZXlfMSI6InBhcmFtX3ZhbHVlXzEiLCJwYXJhbV9rZXlfMiI6InBhcmFtX3ZhbHVlXzIifQ==",
  "SIGN_TIME": 1503639320833,
  "SIGN_STRING": "87efeefc53bb259c11e21ab0223ef2df"
}

Ответ содержит:

  • VENDOR_TRANS_ID - Идентификатор платежа в биллинг системе поставщика услуг
Пример ответа биллинг системы поставщика услуг
{
  "ERROR": "0",
  "ERROR_NOTE": "Success",
  "VENDOR_TRANS_ID": 99987262
}

Уведомление о статусе платежа (Notify)​

Данным запросом система PaySys уведомляет о смене статуса платежа. Только после получения этого запроса биллинг система поставщика должна завершить/отменить платеж.

Запрос содержит

  • AGR_TRANS_ID - Идентификатор платежа в системе PaySys
  • VENDOR_TRANS_ID - Идентификатор платежа в биллинг системе поставщика услуг
  • STATUS - Статус платежа (integer):
    2 - Платеж успешно проведен
    3 - Платеж отменен
    -1 - Ошибка
  • MESSAGE - Описание ошибки (string) (Поле добавляется только при статусе -1)
  • SIGN_TIME - Время подписания запроса в миллисекундах
  • SIGN_STRING - Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS _ID . STATUS . SIGN_TIME ) , где SECRET_KEY секретный ключ поставщика услуг.
Пример запроса
{
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": 1503642925906,
  "STATUS": 2,
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}
Пример ответа биллинг системы поставщика услуг
{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

Отмена платежа (Cancel)​

Если пользователь запросил возврат средств за платеж, этот метод используется для уведомления об отмене платежа. После его выполнения, система PaySys также отправить запрос с уведолением о завершении платежа со статусом отмены платежа.

Запрос содержит:

  • AGR_TRANS_ID - Идентификатор платежа в системе PaySys
  • VENDOR_TRANS_ID - Идентификатор платежа в биллинг системе поставщика услуг
  • SIGN_TIME - Время подписания запроса в миллисекундах
  • SIGN_STRING - Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS _ID . SIGN_TIME ), где SECRET_KEY секретный ключ поставщика услуг.
Пример запроса
{
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": 1503642925906,
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}
Пример ответа биллинг системы поставщика услуг
{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

Отчет о платежах (Statement)​

Данным запросом система PaySys ежемесячно собирает данные о платежах из биллинг системы поставщика услуг. Если какие-то платежи в биллинг системе утеряны/имеют неправильный в системе PaySys создается отчет о расхождениях и ошибки по этим платежам разрешаются вручную.

Запрос содержит:

  • FROM - Время начала периода отчетности в миллисекундах
  • TO - Время окончания периода отчетности в миллисекундах
  • SIGN_TIME - Время подписания запроса в миллисекундах
  • SIGN_STRING - Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . FROM . TO . SIGN_TIME ) , где SECRET_KEY секретный ключ поставщика услуг.
Пример запроса
{
  "FROM": 1503644593249,
  "TO": 1503644893249,
  "SIGN_TIME": 1503644593249,
  "SIGN_STRING": "9ebd383b64eba725ef323e18fcfe9d2f"
}

Ответ содержит:

  • TRANSACTIONS - Список транзакций
    • ENVIRONMENT - "live" - действительные платежи; "sandbox" - тестовые платежи.
    • AGR_TRANS_ID - Идентификатор платежа в системе PaySys
    • VENDOR_TRANS_ID - Идентификатор платежа в биллинг системе поставщика услуг
    • MERCHANT_TRANS_ID - Идентификатор заказа (лицевого счета, подписки, пользователя) (string) в биллинг системе поставщика услуг
    • MERCHANT_TRANS_AMOUNT - Сумма оплаты
    • STATE - Статус платежа
    • DATE - Дата создания платежа в миллисекундах
Пример ответа биллинг системы поставщика услуг
{
  "ERROR": "0",
  "ERROR_NOTE": "Success",
  "TRANSACTIONS": [
    {
      "ENVIRONMENT": "live",
      "AGR_TRANS_ID": 345264652,
      "VENDOR_TRANS_ID": 67879769,
      "MERCHANT_TRANS_ID": "7",
      "MERCHANT_TRANS_AMOUNT": 1000,
      "STATE": 2,
      "DATE": 1480056082732
    },
    {
      "ENVIRONMENT": "sandbox",
      "AGR_TRANS_ID": 775264652,
      "VENDOR_TRANS_ID": 52879769,
      "MERCHANT_TRANS_ID": "7",
      "MERCHANT_TRANS_AMOUNT": 2000,
      "STATE": 3,
      "DATE": 1480076082732
    }
  ]
}

Статус платежа в системе PaySys​

Биллинг система поставщика услуг может узнать статус платежа в системе PaySys, отправив запрос по адресу https://paysys.uz/pay_api/payment_status методом POST в формате JSON .

Пример запроса от биллинг системы поставщика услуг в формате CURL
curl -X POST -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 -d "{\"VENDOR_ID\":902345,\"AGR_TRANS_ID\":1503642925905,\"VENDOR_TRANS_ID\":1503642925906,\"PAYMENT_ID\":1,\"SIGN_TIME\":1503642926295,\"SIGN_STRING\":\"5a30fbd0fab44be29310e4b493c9a287\"}" \
 https://paysys.uz/pay_api/payment_status

Запрос содержит:

  • VENDOR_ID - Идентификатор поставщика услуг в системе PaySys
  • AGR_TRANS_ID - Идентификатор платежа в системе PaySys
  • VENDOR_TRANS_ID - Идентификатор платежа в биллинг система поставщика услуг
  • PAYMENT_ID - Идентификатор платежной системы в системе PaySys
  • SIGN_TIME - Время подписания запроса в миллисекундах
  • SIGN_STRING - Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_ID . PAYMENT_ID . SIGN_TIME ) , где SECRET_KEY секретный ключ поставщика услуг.
Пример запроса
{
  "VENDOR_ID": 902345,
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": 1503642925906,
  "PAYMENT_ID": 1,
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}
Пример ответа агрегатора платежей PaySys
{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

В случае проблем с платежом вернет код ошибки

Пример ответа с ошибкой
{
  "ERROR": "-9",
  "ERROR_NOTE": "Transaction cancelled"
}