Эквайринг (оплата) для UzCard/HUMO

URL шлюза оплаты

https://paysys.uz/gateway

Этапы процесса информационного взаимодействия отображены на диаграмме:

Регистрация карты пользователя

Название метода: paysys.card_registration
Авторизация: требуется

Регистрация карты пользователя в системе PaySys позволяет в дальнейшем оплачивать товары и услуги без СМС подтверждения. После успешной регистрации система партнера получит токен карты пользователя, который можно использовать в запросах для платежей, передавая их в заголовке запроса.

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

phone_number - Номер телефона пользователя, 12 цифр в формате 998907702150
card_number - Номер карты
card_expire - Даты срока истечения карты. Формат даты YYMM

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

{
  "method": "paysys.card_registration",
  "params": {
    "phone_number": "998907702150",
    "card_number": "8600330410689500",
    "card_expire": "2304"
  },
  "id": "0d61b196-9575-11ec-b909-0242ac120002"
}

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

id - Идентификатор карты в системе PaySys
masked_phone_number - Номер телефона, на который был отправлен СМС код для завершения платежа
time_out - Время жизни СМС кода для подтверждения операции
mx_id - Трекер запроса

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

{
  "id": "0d61b196-9575-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "masked_phone_number": "+99890*****50",
    "time_out": 120
  },
  "mx_id": "60b9408332261f741449e42fe6903eac"
}

В случае некорректных параметров запроса система вернет ошибку.

Подтверждение регистрации карты

Название метода: paysys.card_confirm
Авторизация: требуется

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

card_id - Идентификатор карты в системе PaySys
confirmation_code - Код подтверждения, полученный пользователем из СМС

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

{
  "method": "paysys.card_confirm",
  "params": {
    "card_id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "confirmation_code": "254004"
  },
  "id": "c183b8b2-9576-11ec-b909-0242ac120002"
}

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

card_token - Токен карты (возвращается NULL если при регистрации карты параметр phone_number не был отправлен или номер не соответствует номеру, привязанного к этой карте)
card_data - Объект с детальной информацией о карте
- id - Идентификатор карты в системе PaySys
- username - Логин пользователя в системе PaySys
- pan - Номер карты
- expiry - Дата истечения срока действия карты. Формат даты YYMM
- status - Статус карты.
- phone - Номер телефона пользователя, 12 цифр в формате 998907702150
- fullName - ФИО пользователя
- balance - Сумма баланса карты в тиинах
- sms - Флаг, смс уведомления
  true – Карта активна, подключено смс уведомление.
  false – Не подключено смс уведомление.
mx_id - Трекер запроса

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

{
  "id": "c183b8b2-9576-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "card_token": "reethaa7ae2jooqee90t2neiloh8wai2jo",
    "card_data": {
      "id": "6A0A002A1289688F2CDA1F1C0686359C16",
      "username": "aloqa",
      "pan": "860033******1501",
      "expiry": "2304",
      "status": 0,
      "phone": "998907702150",
      "fullName": "TEST TEST2",
      "balance": 200000,
      "sms": true
    }
  },
  "mx_id": "27e8b6197f146e0ab14d01fe7ba6f362"
}

В случае некорректных параметров запроса система вернет ошибку.

Подготовка к онлайн оплате

Название метода: pam.prepare_payment
Авторизация: требуется

Онлайн оплату можно провести по номеру карты и по ее идентификатору в системе PaySys.

Для оплаты по номеру карты необходимо отправить ее номер и дату ее истечения.
Для оплаты по Идентификатору карты достаточно отправить ее id.
После запроса метода, на телефон пользователя будет отправлен код подтверждения, которым пользователь подтвердит платеж.
В случае если к карте оплаты не привязан номер телефона, метод вернет ошибку с кодом -32311

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

Данные карты
- card_id - Идентификатор карты в системе PaySys
  или
- card_number - Номер карты
- card_expire - Дата истечения срока действия карты. Формат даты YYMM
phone_number - Номер телефона пользователя, 12 цифр в формате 998907702150
amount - Сумма в тиинах
vendor_id - Идентификатор площадки по предоставлению услуг
product - Идентификатор заказа (лицевого счета, подписки, пользователя)
comment - Комментарии к оплате
hold - Статус холдирования (true | false)
holding_time - Период времени для холдирования в секундах, начиная с момента создания транзакции
after_expired - Операция после истечения срока холдирования
accept - Списать средства по окончанию срока
cancel - Вернуть средства по окончанию срока
save - Флаг сохранения карты
true - Сохранить карту оплаты в системе PaySys - после подтверждения оплаты, система PaySys вернет идентификатор и токен карты
false - Не сохранять карту оплаты (по умолчанию)

Пример запроса с использованием номера карты

{
  "method": "pam.prepare_payment",
  "params": {
    "card_number": "8601312960622192",
    "card_expire": "2302",
    "phone_number": "998907702150",
    "amount": 100000,
    "vendor_id": 100381,
    "product": "11011bd8-955d-11ec-b909-0242ac120002",
    "comment": "Month subscription",
    "hold": true,
    "holding_time": 604800,
    "after_expired": "accept",
    "save": true
  },
  "id": "bb2656ec-955c-11ec-b909-0242ac120002"
}

Пример запроса с использованием идентификатора карты

{
  "method": "pam.prepare_payment",
  "params": {
    "card_id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "phone_number": "998907702150",
    "amount": 100000,
    "vendor_id": 100381,
    "product": "11011bd8-955d-11ec-b909-0242ac120002",
    "hold": true,
    "holding_time": 604800,
    "after_expired": "accept",
    "save": true
  },
  "id": "bb2656ec-955c-11ec-b909-0242ac120002"
}

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

bank_transaction_id - Номер транзакции в системе PaySys
masked_phone_number - Номер телефона, на который был отправлен СМС код для завершения платежа
time_out - Время жизни СМС кода для подтверждения операции
mx_id - Трекер запроса

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

{
  "id": "bb2656ec-955c-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "bank_transaction_id": 1485295,
    "masked_phone_number": "+99890*****50",
    "time_out": 120
  },
  "mx_id": "be5bf35a31e58b1d1cf176c4c4574028"
}

В случае некорректных параметров запроса система вернет ошибку.

Подтверждение онлайн оплаты

Название метода: pam.confirm_payment
Авторизация: требуется

В случае передачи некорректного кода подтверждения или срок действия кода истек, метод вернет ошибку с кодом -32308.

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

bank_transaction_id - Номер транзакции в системе PaySys
confirmation_code - Код подтверждения платежа, полученный через СМС

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

{
  "method": "pam.confirm_payment",
  "params": {
    "bank_transaction_id": 1485295,
    "confirmation_code": "253890"
  },
  "id": "67f922e4-955f-11ec-b909-0242ac120002"
}

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

details - Объект с деталями проведенного платежа
- id - Промежуточный идентификатор запроса
- masked_card_number - Номер карты
- transaction_id - Идентификатор транзакции в системе PaySys
- bank_transaction_id - Номер транзакции в системе PaySys
- reference_number - Идентификатор транзакции процессингового центра
- merchantId - Идентификатор поставщика услуг в системе UZCARD ONLINE/HUMO
- terminalId - Идентификатор терминала в системе UZCARD ONLINE/HUMO
- amount - Сумма транзакции в тиинах
- date - Дата создания транзакции в секундах
card - Объект с данными карточки(присутсвует только если указан флаг save: true при подготовке оплаты)
- id - Идентификатор карты оплаты
- token - Токен карты оплаты - используется для оплаты без подтверждения платежа кодом по СМС
mx_id - Трекер запроса

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

{
  "id": "67f922e4-955f-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "details": {
      "id": "1429072927",
      "masked_card_number": "860053******9500",
      "transaction_id": "167075",
      "bank_transaction_id": "232288",
      "reference_number": "003136441185",
      "amount": 100000,
      "merchantId": "900000000",
      "terminalId": "97000000",
      "date": 1645700612
    },
    "card": {
      "id": "6A0A002A1289688F2CDA1F1C0686359C16",
      "token": "f0bc2c517a194f148b76a965dd6b51be03a32917"
    }
  },
  "mx_id": "a814f53ab2d9c597e8c8391a73e1980e"
}

В случае некорректных параметров запроса система вернет ошибку.

Подтверждение или отмена захолдированной транзакции

Название метода: hold.confirm
Авторизация: требуется

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

bank_transaction_id - Номер транзакции в системе PaySys
status - Статус
accept - Подтвердить завершение платежа
cancel - Вернет деньги обратно

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

{
  "id": "bb2656ec-955c-11ec-b909-0242ac120002",
  "method":"hold.confirm",
  "params":{
    "bank_transaction_id" : "108137783",
    "status" : "accept"
  }
}

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

status - Статус платежа
2 - Платеж завершен
1 - В ожидании оплаты
3 - Отмена
6 - Возврат
7 - Платеж захолдирован
0 - Платеж создан
-1 - Ошибка
mx_id - Трекер запроса

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

{
  "id": "bb2656ec-955c-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "status": 2
  },
  "mx_id": "c147dbab49736626fde2c2330a4f7353"
}

В случае некорректных параметров запроса система вернет ошибку.

Проверка статуса платежа

Название метода: pam.check_payment
Авторизация: требуется

Проверка статуса платежа необходима, чтобы убедиться, что платеж прошел успешно.

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

agr_transaction_id - Номер транзакции в системе PaySys

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

{
  "method": "pam.check_payment",
  "params": {
    "agr_transaction_id": 6081070
  },
  "id": "e4db6fae-4e58-4469-b442-092ee2ff3370"
}

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

bank_transaction_id - Номер транзакции в системе PaySys
- status - Статус платежа
  2 - Платеж завершен
  1 - В ожидании оплаты
  3 - Отмена
  6 - Возврат
  7 - В ожидании подтверждения
  0 - Платеж создан
  -1 - Ошибка
amount - Сумма платежа в тиинах
date - Дата создания транзакции в секундах
mx_id - Трекер запроса

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

{
  "id": "e4db6fae-4e58-4469-b442-092ee2ff3370",
  "error": null,
  "result": {
    "bank_transaction_id": "101177326",
    "status": "2",
    "amount": 189500,
    "date": 1664875679
  },
  "mx_id": "f71869d3a0baff3cbab8e1e7e1c46855"
}

В случае не корректных параметров запроса система вернет ошибку.

Онлайн оплата с использованием идентификатора и токена карты

Название метода: pam.payment
Авторизация: требуется
Токен карты: требуется

Этот метод не требует подтверждение платежа пользователем. При отправке запроса в его заголовок необходимо добавить токен карты.

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

card_id - Идентификатор карты в системе PaySys
phone_number - Номер телефона пользователя, 12 цифр в формате 998907702150
amount - Сумма платежа в тиинах
vendor_id - Идентификатор площадки по предоставлению услуг
product - Идентификатор заказа (лицевого счета, подписки, пользователя)
hold - Статус холдирования (true | false)
holding_time - Период времени для холдирования в секундах, начиная с момента создания транзакции
after_expired - Операция после истечения срока холдирования
accept - Списать средства по окончанию срока
cancel - Вернуть средства по окончанию срока

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

{
  "method": "pam.payment",
  "params": {
    "card_id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "phone_number": "998907702150",
    "amount": 100000,
    "vendor_id": 100381,
    "hold": true,
    "holding_time": 604800,
    "after_expired": "accept",
    "product": "5d1a3442-d031-4683-8d77-165c4cfc8a9b"
  },
  "id": "77051b9a-f12f-40b0-8ad6-4805ce6121d6"
}

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

details - Объект с деталями проведенного платежа
- id - Идентификатор карты в системе PaySys
- masked_card_number - Номер карты
- transaction_id - Идентификатор транзакции в системе PaySys
- bank_transaction_id - Номер транзакции в системе PaySys
- reference_number - Идентификатор транзакции процессингового центра
- merchantId - Идентификатор поставщика услуг в системе UZCARD ONLINE/HUMO
- terminalId - Идентификатор терминала в системе UZCARD ONLINE/HUMO
- amount - Сумма транзакции в тиинах
- date - Дата создания транзакции в секундах
mx_id - Трекер запроса

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

{
  "id": "77051b9a-f12f-40b0-8ad6-4805ce6121d6",
  "error": null,
  "result": {
    "details": {
      "id": "6A0A002A1289688F2CDA1F1C0686359C16",
      "masked_card_number": "860053******9500",
      "transaction_id": 167075,
      "bank_transaction_id": 232288,
      "reference_number": "003136441185",
      "amount": 100000,
      "merchantId": "900000000",
      "terminalId": "97000000",
      "date": 1645769446
    }
  },
  "mx_id": "e679b1177515ddb621d1fedcbfbc8a6a"
}

В случае некорректных параметров запроса система вернет ошибку.

Отмена оплаты с ипользованием идентфикатора транзакции

Название метода: transaction.reverse
Авторизация: требуется

REVERSE - возможно сделать максимум в течении 1 месяца. Если более, то отмена будет невозможна.

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

transaction_id - Идентификатор транзакция в системе PaySys

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

{
  "method": "transaction.reverse",
  "params": {
    "transaction_id": 7508737
  },
  "id": "5a602cad-4425-4092-9653-f8779ca110ef"
}

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

id - Идентификатор транзакция в системе PaySys
ref_num - Идентификатор транзакции процессингового центра
mx_id - Трекер запроса

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

{
  "id": "5a602cad-4425-4092-9653-f8779ca110ef",
  "error": null,
  "result": {
    "id": 7508737,
    "ref_num": "014173418653"
  },
  "mx_id": "e679b1177515ddb621d1fedcbfbc8a6a"
}

В случае некорректных параметров запроса система вернет ошибку.

Возврат платежа

Название метода: paysys.uz_adjustments
Авторизация: требуется

Частичный возврат средств по картам UzCard/HUMO платный. % За возврат обговаривается при подключении услуги.
Можно проводить любое число возвратов при условии, что сумма всех возвратов меньше либо равна сумме исходного платежа, с учетом удерживаемой комиссии за возврат.
При возврате комиссия может возлагаться как на поставщика услуг, так и на плательщика (тело транзакции).

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

transaction_id - Номер транзакции в системе PaySys
amount - Сумма возврата в тиинах. Не может превышать сумму платежа

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

{
  "method":"paysys.uz_adjustments",
  "params": {
    "transaction_id": "1485295",
    "amount": 113305,
  },
  "id": "69810651-2402-4af7-a245-77e488f21b2b"
}

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

error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
id - Номер транзакции возврата в системе PaySys
status - Статус платежа
6 - Возврат средств
transaction_id - Номер транзакции в системе PaySys
ref_num - Идентификатор транзакции процессингового центра
date - Время возврата
mx_id - Трекер запроса

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

{
  "id": "69810651-2402-4af7-a245-77e488f21b2b",
  "error": null,
  "result": {
    "id": "19761",
    "status": 6,
    "transaction_id": "1485295",
    "ref_num": "014173418653",
    "date": "1679746807",
  },
  "mx_id": "3a2cb35465234942e24268421703f679"
}

В случае некорректных параметров запроса система вернет ошибку.

Отправить смс повторно с ипользованием идентфикатора транзакции

Название метода: pam.pay_resend_sms
Авторизация: требуется

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

transaction_id - Идентификатор транзакция в системе PaySys

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

{
   "method" : "pam.pay_resend_sms",
   "params": {
       "bank_transaction_id": 119600681
   },
   "id": "5a602cad-4425-4092-9653-f8779ca110ef"
}

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

id - Идентификатор транзакция в системе PaySys
confirmation_code - Объект с деталями отправки смс
- status - Статус отправки
- time_out - Тайм-аут
mx_id - Трекер запроса

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

{
    "id": "5a602cad-4425-4092-9653-f8779ca110ef",
    "error": null,
    "result": {
    "confirmation_code": {
        "status": "sent",
        "time_out": 300
       }
    }
    "mx_id": "e679b1177515ddb621d1fedcbfbc8a6a"
}

В случае некорректных параметров запроса система вернет ошибку.

Тестирование запросов

Протестировать запросы API (Mockup сервер) также можно через Postman:

Скачайте коллекцию запросов: API шлюза оплаты PaySys.postman_collection
Скачайте окружения для выполнения запросов: PaySys-Gateway.postman_environment.json
Импортируйте коллекции в приложении Postman
Импортируйте окружение
Перейдите в импортированную коллекцию и выберите в правом верхнем углу окружение PaySys Gateway
Справа также есть иконка </> code, кликнув по которой можно посмотреть запрос в разных форматах (cURL, HTTP и т.д.)
Внизу слева есть >_ Console, в которой отображаются выполненные запросы

Эквайринг (оплата) для UzCard/HUMO

Этапы процесса информационного взаимодействия отображены на диаграмме:​

Регистрация карты пользователя​

Подтверждение регистрации карты​

Подготовка к онлайн оплате​

Подтверждение онлайн оплаты​

Подтверждение или отмена захолдированной транзакции​

Проверка статуса платежа​

Онлайн оплата с использованием идентификатора и токена карты​

Отмена оплаты с ипользованием идентфикатора транзакции​

Возврат платежа​

Отправить смс повторно с ипользованием идентфикатора транзакции​

Тестирование запросов​

Этапы процесса информационного взаимодействия отображены на диаграмме:

Регистрация карты пользователя

Подтверждение регистрации карты

Подготовка к онлайн оплате

Подтверждение онлайн оплаты

Подтверждение или отмена захолдированной транзакции

Проверка статуса платежа

Онлайн оплата с использованием идентификатора и токена карты

Отмена оплаты с ипользованием идентфикатора транзакции

Возврат платежа

Отправить смс повторно с ипользованием идентфикатора транзакции

Тестирование запросов