Эквайринг (оплата) для международных карт

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

https://paysys.uz/gateway

Внимание!

Необходима PCI DSS сертификация поставщика услуг.

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

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

Агрегатор платежей PaySys предоставляет возможность онлайн оплаты картой Visa, MasterCard, MIR.

Этот метод подготавливает платеж и возвращает ссылку на страницу с подтверждением платежа при помощи 3DS.

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

card_holder_name - Имя владельца карты, допустимые символы [0-9a-zA-Z-/ _.]{1,26}
card_number - Номер карты
card_expire - Даты срока истечения карты. Формат даты YYMM
card_cvc - Значение CVC карты, 3 цифры
amount - Сумма платежа в центах доллара/евро, копейках рубля
currency - Валюта платежа. Доступны валюты:
uzs - Узбекский сум - минимум 1000 сум, максимум 75 000 000 сум - валюта по умолчанию
usd - Доллар США - минимум 1$, максимум 5000$
eur - Евро - минимум 1€, максимум 5000€
rub - Российский рубль - минимум 1₽, максимум - не ограничено
hold - Статус холдирования (true | false)
holding_time - Период времени для холдирования в секундах, начиная с момента создания транзакции
after_expired - Операция после истечения срока холдирования
accept - Списать средства по окончанию срока
cancel - Вернуть средства по окончанию срока
vendor_id - Идентификатор площадки по предоставлению услуг
partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
client_ip_addr - IP адрес клиента
description - Краткое описание платежа (до 125 знаков)
redirect_url - URL ссылки сайта поставщика, куда будет перенаправлен пользователь после завершения оплаты (не обязателен)

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

{
  "method": "paysys.prepare_payment",
  "params": {
    "card_holder_name": "CARDHOLDER NAME",
    "card_number": "4278000000275400",
    "card_expire": "2702",
    "card_cvc": "067",
    "amount": "1139000",
    "currency": "uzs",
    "vendor_id": "100381",
    "partner_trans_id": "167075",
    "client_ip_addr": "192.4.59.3",
    "description": "Month subscription",
    "redirect_url": "https://shop.merchant.com/order/23"
  },
  "id": "85e0cd56-52c9-4709-b558-81203cb4e6ff"
}

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

transaction_id - Номер транзакции в системе PaySys
confirm_url - URL для ввода проверочного кода 3DS.
mx_id - Трекер запроса

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

{
  "id": "85e0cd56-52c9-4709-b558-81203cb4e6ff",
  "error": null,
  "result": {
    "transaction_id": "1485295",
    "confirm_url": "https://ecomm.kapital24.uz:6443/ecomm2/ClientHandler?trans_id=tYkiAVsnP3SnjBMSiXrWGrIRbeo%3D"
  },
  "mx_id": "2c2a35dc3682fc7e94df5b2f61a10c6b"
}

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

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

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

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

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

partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)

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

{
  "method": "paysys.check_payment",
  "params": {
    "partner_trans_id": "167075"
  },
  "id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17"
}

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

transaction_id - Номер транзакции в системе PaySys
partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
data - Ответ системы Visa, MasterCard, MIR по операции (используется для отладки)
err_obj - Если статус платежа -1, то параметр err_obj будет содержать код ошибки code и описание ошибки message , а ином случаи err_obj будет равен null

{ 
  "code": -32313, 
  "message": "Статус транзакции отмененный"
}

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

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

{
  "id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17",
  "error": null,
  "result": {
    "transaction_id": "1485295",
    "partner_trans_id": "167075",
    "status": "2",
    "data": {
      "RESULT": "OK",
      "RESULT_CODE": "000",
      "3DSECURE": "AUTHENTICATED",
      "RRN": "207011889463",
      "APPROVAL_CODE": "155427",
      "CARD_NUMBER": "427831******5400"
    },
    "err_obj": null
  },
  "mx_id": "8e23e530e81f6b777efa19f4c7e1e007"
}

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

Регистрация международной карты

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

Система PaySys предоставляет возможность регистрации международной карты Visa, MasterCard, MIR.

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

card_number - Номер карты
card_expire - Даты срока истечения карты. Формат даты YY/MM
card_cvc - Значение CVC карты
card_holder - Имя владельца карты, допустимые символы [0-9a-zA-Z-/ _.]{1,26}
account - Учётная запись
id - Идентификатор запроса

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

{
  "method": "mir.card_registration",
  "params": {
    "card_number": "2222222222222222",
    "card_expire": "04/27",
    "card_cvc": "XXX",
    "card_holder": "CARDHOLDER NAME",
    "account": "998123456789"
  },
  "id": 2
}

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

error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
card_id - Идентификатор карты в системе PaySys
confirm_url - URL для ввода проверочного кода 3DS
id - Идентификатор запроса
mx_id - Трекер запроса

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

{
  "error": null,
  "result": {
    "card_id": "722c379bbe7646446483813c88f3883c",
    "confirm_url": "https://paysys.uz/Security3d/qiwi/caea6ec14e8dee23ca8c68b69565fa9a"
  },
  "id": 2,
  "mx_id": "bd9e122dae9cabfa97b0bb8e468e3b63"
}

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

Данным запросом система PaySys уведомляет о статусе регистрации карты.

Запрос отправляется системой PaySys. Если колбэк-функция содержит статус SUCCESS, то регистрация успешно завершена.

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

stat - Статус
id - Идентификатор карты в системе PaySys
token - Токен карты
pan - Номер карты

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

{
  "id": "34a83544-81f8-4804-b6b7-07044a1600ca",
  "method": "partner.notify",
  "params": {
    "stat": "SUCCESS",
    "id": "d553921350e68a6af96d63a544720f9c",
    "token": "0b6227c70d365255176cb6c3b9b6cccfd3aa17b0",
    "pan": "222222******2222"
  }
}

Ответ должен быть обязательным, чтобы удостовериться о получения запроса системы PaySys.

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

error - Если метод выполнился без ошибок праметр будет равен NULL

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

{
  "error": null
}

В случае возникновения ошибки, запрос будет содержать статус ERROR и ee описание.

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

stat - Статус
id - Идентификатор карты в системе PaySys
code - Код ошибки
message - Описание ошибки

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

{
  "id": "34a83544-81f8-4804-b6b7-07044a1600ca",
  "method": "partner.notify",
  "params": {
    "stat": "ERROR",
    "id": "d553921350e68a6af96d63a544720f9c",
    "code": "-34000",
    "message": "Описание ошибки"
  }
} 

Ответ должен быть обязательным, чтобы удостовериться о получения запроса системы PaySys.

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

error - Если метод выполнился без ошибок праметр будет равен NULL

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

{
  "error": null
}

Удаление токена карты

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

Система PaySys предоставляет возможность удалить токен карту, при необходимости.

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

card_id - Идентификатор карты в системе PaySys
card_token - Токен карты
id - Идентификатор запроса

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

{
  "method": "mir.remove_card_token",
  "params": {
    "card_id": "49270cae102c3c3197da8d0086a28c15",
    "card_token": "6b7b30a481e66bad08de64f3145cf7ce"
  },
  "id": "288175fc-6d5b-4179-b598-defec67abbaa"
}

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

error - Если метод выполнился без ошибок праметр будет равен NULL
pan - Номер карты
id - Идентификатор запроса

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

{
  "error": null,
  "result": {
    "pan": "222222******2222"
  },
  "id": "288175fc-6d5b-4179-b598-defec67abbaa"
}

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

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

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

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

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

partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
card_id - Идентификатор карты в системе PaySys
amount - Сумма выплаты
currency - Валюта платежа
client_ip_addr - IP адрес клиента
description - Описание платежа
vendor_id - Идентификатор поставщика
id - Идентификатор запроса

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

{
  "method": "paysys.pay_by_id",
  "params": {
    "partner_trans_id": "39888c6d-bbb9-4044-97a6-bec2d85dd6c10",
    "card_id": "722c379bbe7646446483813c88f3883c",
    "amount": "100",
    "currency": "RUB",
    "client_ip_addr": "1.1.1.1",
    "description": "TEST",
    "vendor_id": "101478"
  },
  "id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17"
}

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

error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
id - Идентификатор банковской транзакции RRN (Reference Retrieval Number)
masked_card_number - Номер карты
transaction_id - Идентификатор платежа в системе PaySys
bank_transaction_id - Номер транзакции в системе PaySys
amount - Сумма выплаты
merchantId - Идентификатор поставщика услуг
terminalId - Идентификатор терминала
date - Дата создания транзакции в секундах
payment_id - Идентификатор платежной системы в системе PaySys
id - Идентификатор запроса
mx_id - Трекер запроса

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

{
  "error": null,
  "result": {
    "details": {
      "id": 217909211968,
      "masked_card_number": "222222******2222",
      "transaction_id": "4457089",
      "bank_transaction_id": 100053825,
      "amount": "100,00",
      "merchantId": null,
      "terminalId": null,
      "date": 1656407767
    },
    "payment_id": 27
  },
  "id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17",
  "mx_id": "007ed8fddeffb2301b7a0c21d968b9b4"
}

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

Отмена платежа

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

Отмена (reversal, adjustements) платежа возможна в течении 7 дней, единожды, с момента операции (желательно до «закрытия бизнес дня»).
Схема работы отмены: во время оплаты сумма по платежу блокируется (блок с минусом) для карты и становится недоступной для клиента (ждет клиринга, чтобы списать средства окончательно).
Если поставщик услуг отменил платеж (reversal), то на карте появляется блокировка с плюсом, которая аннулирует первую блокировку (блок с минусом). Ранее заблокированная сумма на карте становиться доступной.
Если клиент не видит блокировку с плюсом и средства по-прежнему не доступны, то нужно обратиться в банк-эмитент, который выпустил эту карту и запросить причину, по которой платеж не был отменен.

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

partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)

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

{
  "method": "paysys.cancel_payment",
  "params": {
    "partner_trans_id": "167075"
  },
  "id": "73a32f5c-9dca-446e-afa9-22eb5602954c"
}

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

error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
transaction_id - Номер транзакции в системе PaySys
partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
data - Ответ системы Visa, MasterCard, MIR по операции (используется для отладки)
status - Статус платежа
3 - Платеж отменен
mx_id - Трекер запроса

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

{
  "id": "73a32f5c-9dca-446e-afa9-22eb5602954c",
  "error": null,
  "result": {
    "transaction_id": "1485295",
    "partner_trans_id": "167075",
    "status": "3",
    "data": {}
  },
  "mx_id": "6c2c9a196ab97334382bf23a7d3430ab"
}

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

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

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

Возврат средств (refund) по платежу возможен, с момента операции (желательно после «закрытия бизнес дня»).
Можно проводить любое число возвратов при условии, что сумма всех возвратов меньше либо равна сумме исходного платежа, с учетом удерживаемой комиссии. При вовзратах комиссия эквайера не возвращается.
Схема работы метода возврата: после инициализации операции возврата платежа (refund) поставщиком услуг, сумма приходит на карту клиента вместе с клирингом.
Этот процесс обычно занимает 3 (три) рабочих дня. Но зависит от политики банка-эквайера, в котором обслуживается компания поставщика услуг и от банка-эмитента, в котором была выпущена карта. В обоих банках должна пройти процедура клиринга.
Сумма возврата средств зависит от издержек поставщика услуг по процедуре возврата и обычно меньше суммы платежа.

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

partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
amount - Сумма возврата в центах доллара. Не может превышать сумму платежа
currency - Валюта платежа. Доступны валюты:
uzs - Узбекский сум - валюта по умолчанию
usd - Доллар США
eur - Евро
rub - Российский рубль

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

{
  "method": "paysys.refund_payment",
  "params": {
    "partner_trans_id": "167075",
    "amount": "113305",
    "currency": "uzs"
  },
  "id": "69810651-2402-4af7-a245-77e488f21b2b"
}

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

error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
transaction_id - Номер транзакции в системе PaySys
partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
data - Ответ системы Visa, MasterCard, MIR по операции (используется для отладки)
status - Статус платежа
6 - Возврат средств
mx_id - Трекер запроса

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

{
  "id": "69810651-2402-4af7-a245-77e488f21b2b",
  "error": null,
  "result": {
    "transaction_id": "1485295",
    "partner_trans_id": "167075",
    "status": "6",
    "data": {}
  },
  "mx_id": "3a2cb35465234942e24268421703f679"
}

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

Уведомление о статусе транзакции

HTTP заголовок: "Authorization: Basic " + base64_encode(VENDOR_METHOD + ":" + VENDOR_SECRET_KEY)

Данным запросом система PaySys уведомляет о статусе транзакции. Запрос отправляется системой PaySys.

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

id - Идентификатор транзакции в системе PaySys
account - Идентификатор платежа системе партнера
amount - Сумма выплаты
card_masked - Номер карты
currency - Код валюты
currency_name - Наименование валюты
status - Статус платежа
6 - Возврат средств
3 - Платеж отменен
2 - Платеж завершен
1 - В ожидании оплаты
0 - Платеж создан
<0 - Ошибка
date - Дата создания транзакции

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

{
  "id": "44114543",
  "account": "931111111",
  "amount": 1000,
  "card_masked": "222222******2222",
  "currency": 840,
  "currency_name": "usd",
  "status": -1,
  "date": "24.06.2022 07:49:16"
}

Ответ должен быть обязательным, чтобы удостовериться о получения запроса системы PaySys.

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

error - Если метод выполнился без ошибок праметр будет равен NULL

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

{
  "error": null
}

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

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

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

Эквайринг (оплата) для международных карт

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

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

Регистрация международной карты​

Удаление токена карты​

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

Отмена платежа​

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

Уведомление о статусе транзакции​

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

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

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

Регистрация международной карты

Удаление токена карты

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

Отмена платежа

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

Уведомление о статусе транзакции

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