Техническая документация

Процесс оплаты услуг с помощью электронной валютой или банковской картой происходит простым способом через безопасное соединение, что делает всю операцию не только надежной и конфиденциальной, но и быстрой.
  • Покупатель выбирает товар и способ оплаты в Вашем онлайн-магазине и магазин, в свою очередь, подсчитывает сумму к оплате.
  • Payments.Express получает требуемую информацию о сумме и валюте для осуществления платежа.
  • Вы получаете требуемую сумму на кошелек, карту или счет указанный в личном кабинете. После оплаты, покупатель перенаправляется на страницу с оплаченным товаром (URL успешной оплаты).
Форма оплаты
Для инициализации оплаты, магазин должен отправить покупателя по данному адресу с передачей параметров.
Предварительно заполнив параметры (номер счета, сумма, ID проекта)

Action - https://payments.exoress/merchant
Method - POST/GET
Fields - поля передаваемые в форме, описаны в таблице ниже:

Название Параметр Обязательный Описание
ID проекта merchant_id Да ID проекта в системе Payments.Express
Сумма платежа amount Да Сумма к оплате
Валюта платежа currency Нет Валюта платежа по стандарту ISO 4217 (RUB, USD, EUR)
Номер счета pay_id Да Номер платежа в системе продавца
Описание desc Нет Описание платежа
Email email Нет Почтовый ящик покупателя
Телефон phone Нет Номер телефона покупателя
Платёжная система method Нет Способ оплаты платежа (смотрите список платежных систем)
Язык интерфейса lang Нет Язык интерфейса страницы оплаты (ru/en)
Контрольная подпись sign Да Контрольная подпись формы оплаты (формирование контрольной подписи формы)
Дополнительные параметры продавца Определяется продавцом Нет Дополнительные параметры (в сумме до 2048 символов)


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

Формирование подписи производится путем склеивания параметров через ":" и создания контрольной суммы MD5. Склеиваются параметры currency, amount, секретный ключ, merchant_id и pay_id. Включить проверку можете в настройках проекта.
<?php
  $shop_id = '399'; // ID проекта
  $secret_key = 'NLmx0woAqrgHYnMbDSVLChCJ77R8adf'; // Секретный ключ
  $amount = '100.00'; // Сумма к оплате
  $pay_id = '129'; // Номер счета
  $currency = 'RUB'; // Валюта платежа
  $sign = md5($currency.':'.$amount.':'.$secret_key.':'.$shop_id.':'.$pay_id);
?>

Пример формы на PHP:
<?php
  $shop_id = '1399';
  $secret_key = 'NLmx0woAqrgHYnMbDSVLChCJ77R8adf';
  $amount = '100.00';
  $pay_id = '129';
  $currency = 'RUB';
  $sign = md5($currency.':'.$amount.':'.$secret_key.':'.$shop_id.':'.$pay_id);
?>

<form action='https://payments.exoress/merchant' accept-charset='utf-8' method='post'>
  <input type='hidden' name='merchant_id' value=<?php echo $shop_id; ?>>
  <input type='hidden' name='amount' value=<?php echo $amount; ?>>
  <input type='hidden' name='currency' value='RUB'>
  <input type='hidden' name='pay_id' value=<?php echo $pay_id; ?>>
  <input type='hidden' name='desc' value='Техническая документация Payments.Express'>
  <input type='hidden' name='email' value='[email protected]'>
  <input type='hidden' name='method' value='qiwi'>
  <input type='hidden' name='currency' value=<?php echo $currency; ?>>
  <input type='hidden' name='sign' value=<?php echo $sign; ?>>
  <input type=submit value='Купить'>
</form>
Оповещение об оплате
После поступления платежа от ваших покупателей, наш сервис отправляет запрос на URL оповещения, который Вы указали в настройках проекта.
На стороне магазина по адресу URL оповещения должен быть установлен скрипт-обработчик, который проверяет поступившие данные (сумма, номер счета, контрольная подпись).

Action - URL оповещения
Method - POST/GET
Fields - поля передаваемые в форме, описаны в таблице ниже:

Название Параметр Описание
ID проекта merchant_id ID проекта в системе Payments.Express
Идентификатор платежа transaction_id Номер платежа в системе Payments.Express
Номер счета pay_id Номер платежа в системе продавца
Сумма платежа amount Сумма к оплате в рублях
Сумма начисления profit Сумма к зачислению в рублях
Email email Почтовый ящик покупателя
Платежная система method Способ оплаты платежа (смотрите список платежных систем)
Дата и время формирования счета date Дата и время формирования счета в формате ДД.ММ.ГГГГ чч:мм:сс
Дата и время оплаты счета pay_date Дата и время оплаты счета в формате ДД.ММ.ГГГГ чч:мм:сс
Контрольная подпись sign Контрольная сумма md5 (Формирование контрольной подписи)
Дополнительные параметры продавца Определяется продавцом Дополнительные параметры

Проверка IP

Рекомендуем так же проверять IP сервера отправляющего Вам информацию, наши IP: 185.162.128.38, 185.162.128.39, 185.162.128.88.
Пример функции:
<?php
  function getip() {
    if(isset($_SERVER['HTTP_X_REAL_IP'])) return $_SERVER['HTTP_X_REAL_IP'];
    return $_SERVER['REMOTE_ADDR'];
  }
  if (!in_array(getip(), array('185.162.128.38', '185.162.128.39', '185.162.128.88'))) {
    die("hacking attempt!");
  }
?>


Формирование контрольной подписи в обработчике

Формирование подписи производится путем склеивания параметров через ":" и создания контрольной суммы MD5. Склеиваются параметры merchant_id, amount, pay_id и секретный ключ.
<?php
  $shop_id = '2399'; // ID проекта
  $secret_key = 'NLmx0woAqrgHYnMbDSVLChCJ77R8adf'; // Секретный ключ
  $signature = md5($shop_id.':'.$_REQUEST['amount'].':'.$_REQUEST['pay_id'].':'.$secret_key);
?>


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

Данная функция предназначена для автоматического повтора запроса от нашего сервиса к Вашему URL оповещения.
При включении подтверждения платежа наш сервис будет повторять запрос каждую минуту в течение часа, до тех пор пока не получит ответ OK (латиница).

Пример обработчика платежей
<?php
  $shop_id = '2399';
  $secret_key = 'NLmx0woAqrgHYnMbDSVLChCJ77R8adf';
  $signature = md5($shop_id.':'.$_REQUEST['amount'].':'.$_REQUEST['pay_id'].':'.$secret_key);

  function getip() {
     if(isset($_SERVER['HTTP_X_REAL_IP'])) return $_SERVER['HTTP_X_REAL_IP'];
     return $_SERVER['REMOTE_ADDR'];
  }
  if (!in_array(getip(), array('185.162.128.38', '185.162.128.39', '185.162.128.88'))) {
     die("hacking attempt!");
  }

  if ($signature != $_REQUEST['sign']) {
     die('bad sign!');
  }

  // Оплата прошла успешно, можно проводить операцию

  die('OK');
?>
Переадресация при успешной оплате
После успешного проведения платежа, покупатель будет перенаправлен на URL успешной оплаты, который Вы задали в настройках проекта.

Не используйте URL успешной оплаты как скрипт-обработчик!

Action - URL успешной оплаты
Method - POST/GET
Fields - поля передаваемые в форме, описаны в таблице ниже:

Название Параметр Описание
Номер счета pay_id Номер платежа в системе продавца
Сумма платежа amount Сумма к оплате в рублях
Дополнительные параметры продавца Определяется продавцом Дополнительные параметры
Переадресация при неуспешной оплате
После НЕ успешного проведения платежа, Покупатель будет перенаправлен на URL неуспешной оплаты, который Вы задали в настройках проекта.

Action - URL неуспешной оплаты
Method - POST/GET
Fields - поля передаваемые в форме, описаны в таблице ниже:
Название Параметр Описание
Номер счета pay_id Номер платежа в системе продавца
Сумма платежа amount Сумма к оплате в рублях
Дополнительные параметры продавца Определяется продавцом Дополнительные параметры
Список платежных систем
Платежная система Значение
Webmoney wm
Qiwi Wallet qiwi
Яндекс.Деньги ym
Payeer payeer
Единая касса w1
Bitcoin btc
Litecoin ltc
Dash dash
Zcash zec
Perfect Money pm
OKpay okpay
AdvCash advcash
Paxum paxum
Exmo exmo
eCoin ecoin
Visa/MasterCard card
Apple Pay applepay
Google Pay googlepay
Samsung Pay samsungpay
МТС mts
Билайн beeline
Мегафон megafon
Теле2 tele2
Терминалы России term
Банковский перевод bank
CONTACT contact
Юнистрим unistream
API
Для работы с API необходимы API ID {api_id} и API ключ {api_key}, которые доступны в личном кабинете.
Все запросы отправляются методом GET/POST, ответ в формате JSON.
Проверка баланса
Для получения баланса необходимо отправить запрос на URL https://payments.exoress/api/balance/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'balance{api_id}{api_key}')


Пример ответа:
{
    "result": {
        "balance": 15023.66
    }
}
Параметр Значение Описание
balance число Баланс аккаунта в рублях
Получение курсов валют
Для получения текущих курсов конвертации валют необходимо отправить запрос на URL https://payments.exoress/api/rates/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'rates{api_id}{api_key}')


Пример ответа:
{
    "result": {
        "in": {
            "wmz": 64.13,
            "usd": 64.02,
            "eur": 70.52,
            "btc": 474342.45,
            "ltc": 3081.88,
            "dash": 3303.42,
            "zec": 1860.49
        },
        "out": {
            "wmz": 65.07,
            "uah": 2.65
        }
    }
}
Параметр Значение Описание
in/out текст Тип конвертации: на прием (in) или на вывод (out)
wmz/usd/... число Курс конвертации выбранной валюты
Получение комиссиий проекта
Для получения списка комиссий проекта необходимо отправить запрос на URL https://payments.exoress/api/commissions/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
project_id число Да ID проекта в системе Payments.Express
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'commissions{api_id}{project_id}{api_key}')


Пример ответа:
{
    "result": {
        "qiwi": 7.5,
        "ym": 4,
        "wm": 3.9,
        "card": 5,
        "applepay": 5,
        "googlepay": 5,
        "samsungpay": 5,
        "payeer": 4,
        "advcash": 4,
        "pm": 4,
        "btc": 2.5,
        "ltc": 2.5,
        "dash": 2.5,
        "zec": 2.5,
        "mts": 4.5,
        "beeline": 4.5,
        "megafon": 4.5,
        "tele2": 4.5,
        "exmo": 4,
        "term": 6.9
    }
}
Параметр Значение Описание
qiwi/ym/... число Комиссия платежного направления на прием
Получение списка транзакций
Для получения списка транзакций необходимо отправить запрос на URL https://payments.exoress/api/payments/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
project_id число Да ID проекта в системе Payments.Express
trans_id число Нет Номер платежа в системе Payments.Express
pay_id число Нет Номер платежа в системе продавца
offset число Нет Смещение, необходимое для выборки определенного подмножества транзакций (по-умолчанию - 0)
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'payments{api_id}{project_id}{api_key}')


Пример ответа:
{
    "result": {
        "total": 2,
        "payments": {
            "4950030": {
                "transaction_id": 4950030,
                "pay_id": 1335,
                "status": "paid",
                "method": "advcash",
                "amount": 1250,
                "profit": 1200,
                "email": "[email protected]",
                "desc" : "Xiaomi Mi Power Bank",
                "date": "26.11.2019 17:12:02",
                "pay_date": "26.11.2019 17:12:12"
            },
            "4604415": {
                "transaction_id": 4604415,
                "pay_id": 1334,
                "status": "waiting",
                "method": "ltc",
                "amount": 15000,
                "profit": 14600.25,
                "email": "[email protected]",
                "desc": "Apple Airpods 2",
                "date": "26.11.2019 15:32:14",
                "pay_date": ""
            }
        }
    }
}
Параметр Значение Описание
transaction_id число Номер платежа в системе Payments.Express
pay_id число Номер платежа в системе продавца
status строка Статус платежа:
  paid — успешный платеж;
  waiting — ожидание оплаты;
  refund — возврат средств покупателю;
  canceled — платеж отменен;
  expired — истек срок жизни счета;
  error — ошибка платежа
method текст Платежная система
amount число Сумма заказа в рублях
profit число Сумма к зачислению в рублях
email строка Почтовый ящик покупателя
desc строка Описание платежа
date текст Дата и время формирования счета в формате ДД.ММ.ГГГГ чч:мм:сс
pay_date текст Дата и время оплаты счета в формате ДД.ММ.ГГГГ чч:мм:сс
Создание выплаты
Для создания новой выплаты необходимо отправить запрос на URL https://payments.exoress/api/create-payout/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
payout_id число Да Уникальный номер выплаты в системе продавца
payout_type текст Да Платежная система:
  qiwi — Qiwi Wallet;
  ym — Яндекс.Деньги;
  wm — Webmoney (WMZ);
  mc — Мобильный платеж;
  card — Visa/Mastercard/Мир
amount число Да Сумма выплаты в рублях
wallet текст Да Кошелек/Номер карты получателя
currency текст Нет Валюта получателя (банковские карты):
  RUB — российский рубль (по умолчанию);
  UAH — украинская гривна.
commission_type текст Нет Комиссия:
  payment — с суммы платежа;
  balance — с баланса
status_url строка Нет URL на который будет отправлен GET-запрос при переходе выплаты в финальный статус
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'create-payout{api_id}{payout_id}{payout_type}{amount}{wallet}{api_key}')


Пример ответа:
{
    "result": {
        "transaction_id": 97769,
        "payout_id": 10010,
        "payout_type": "qiwi",
        "status": "paid",
        "amount": 5000,
        "commission": 75,
        "commission_type": "payment",
        "wallet": 79770000000,
        "balance": 211165.79,
        "date": "26.11.2019 11:00:59",
        "complete_date": "26.11.2019 11:00:59"
    }
}
Параметр Значение Описание
transaction_id число Номер выплаты в системе Payments.Express
payout_id число Номер выплаты в системе продавца
payout_type текст Платежная система
status строка Статус выплаты:
  paid — успешная выплата;
  in_process — выплата отправлена в платежную систему (временный статус);
  canceled — выплата отменена платежной системой, средства возвращены на баланс;
  blocked — выплата заблокирована системой мониторинга
amount число Сумма выплаты в рублях
commission число Комиссия выплаты
commission_type текст Тип комиссии
rate число Курс конвертации
wallet текст Кошелек/Номер карты получателя
balance число Баланс в системе доступный для выплат
date текст Дата создания выплаты в формате ДД.ММ.ГГГГ чч:мм:сс
complete_date текст Дата завершения выплаты в формате ДД.ММ.ГГГГ чч:мм:сс
Получение списка выплат
Для получения списка выплат необходимо отправить запрос на URL https://payments.exoress/api/payouts/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
trans_id число Нет Номер выплаты в системе Payments.Express
payout_id число Нет Номер выплаты в системе продавца
offset число Нет Смещение, необходимое для выборки определенного подмножества транзакций (по-умолчанию - 0)
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'payouts{api_id}{api_key}')


Пример ответа:
{
    "result": {
        "total": 2,
        "payouts": {
            "97769": {
                "transaction_id": 97769,
                "payout_id": 10005,
                "payout_type": "qiwi",
                "status": "paid",
                "amount": 5000,
                "commission": 75,
                "commission_type": "balance",
                "wallet": 79770000000,
                "date": "26.11.2019 11:45:42",
                "complete_date": "26.11.2019 11:45:42"
            },
            "97554": {
                "transaction_id": 97554,
                "payout_id": 10004,
                "payout_type": "ym",
                "status": "canceled",
                "amount": 15000,
                "commission": 225,
                "commission_type": "payment",
                "wallet": 41001111112111,
                "date": "26.11.2019 11:43:46",
                "complete_date": "26.11.2019 11:43:47"
            }
        }
    }
}
Параметр Значение Описание
transaction_id число Номер выплаты в системе Payments.Express
payout_id число Номер выплаты в системе продавца
payout_type текст Платежная система
status строка Статус выплаты:
  paid — успешная выплата;
  in_process — выплата отправлена в платежную систему (временный статус);
  canceled — выплата отменена платежной системой, средства возвращены на баланс;
  blocked — выплата заблокирована системой мониторинга
amount число Сумма выплаты в рублях
commission число Комиссия выплаты в рублях
commission_type текст Тип комиссии
rate число Курс конвертации
wallet текст Кошелек/Номер карты получателя
date текст Дата создания выплаты в формате ДД.ММ.ГГГГ чч:мм:сс
complete_date текст Дата завершения выплаты в формате ДД.ММ.ГГГГ чч:мм:сс
Получение списка IP адресов сервиса
Для получения списка актуальных IP адресов, с которых отправляются оповещения о платежах, необходимо отправить запрос на URL https://payments.exoress/api/ip-notification/{api_id} со следующими параметрами:
Параметр Значение Обязательный Описание
sign строка Да Подпись запроса. Формируется путем склеивания параметров и создания хэша
hash('sha256', 'ip-notification{api_id}{api_key}')


Пример ответа:
{
    "result": {
        "ip": [ "185.162.128.38", "185.162.128.39", "185.162.128.88" ]
    }
}
Параметр Значение Описание
ip массив Список IP адресов сервиса
Коды ошибок
Код ошибки Описание
100 Неверный формат запроса
101 Ошибка авторизации
102 Неверная контрольная подпись
103 API отключен для данного аккаунта
104 Ограничение по IP адресу
200 Неверный ID проекта
300 Недопустимое платежное направление
301 Некорректный формат кошелька/счета
302 Некорректный тип комиссии
303 Некорректная сумма платежа
304 Некорретный номер выплаты. Идентификатор выплаты должен быть уникальным
305 Недостаточно средств на балансе
306 Сумма выплаты меньше допустимой
307 Сумма выплаты больше допустимой
308 Некорретный формат status url
309 Внутренняя техническая ошибка
310 Операция запрещена для выполнения пользователем