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

Биллинг система поставщика услуг призвана сделать обработку платежей более быстрой и безопасной. Также она позволяет не допустить повторной оплаты заказа и своевременно информировать пользователя о проблемах оплаты. 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"
}

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

PARAMETERS - дополнительные параметры оплаты от биллинг системы. Может быть NULL. Передается в методе уведомления о завершении платежа.

Пример ответа биллинг системы поставщика услуг

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

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

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

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

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

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

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

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

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

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

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

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

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

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